home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / bawk.zip / BAWK.DOC < prev    next >
Text File  |  1986-04-15  |  11KB  |  306 lines
  1. NAME
  2.  
  3.     bawk - text processor
  4.  
  5. SYNOPSIS
  6.  
  7.     bawk rules [file] ...
  8.  
  9. DESCRIPTION
  10.  
  11.     Bawk is a text processing program that searches files for
  12.     specific patterns and performs "actions" for every occurrance
  13.     of these patterns.  The patterns can be "regular expressions"
  14.     as used in the UNIX "ex" editor.  The actions are expressed
  15.     using a subset of the "C" language.
  16.  
  17.     The patterns and actions are usually placed in a "rules" file
  18.     whose name must be the first argument in the command line.
  19.     All other arguments are taken to be the names of text files on
  20.     which the rules are to be applied.
  21.     The special file name "-" may also be used anywhere on the
  22.     command line to take input from the standard input device.
  23.  
  24.     The command:
  25.  
  26.         bawk - prog.c - prog.h
  27.  
  28.     would read the patterns and actions rules from the standard
  29.     input, then apply them to the files "prog.c", the standard
  30.     input and "prog.h" in that order.
  31.  
  32.     The general format of a rules file is:
  33.  
  34.         <pattern> { <action> }
  35.         <pattern> { <action> }
  36.         ...
  37.  
  38.     There may be any number of these <pattern> { <action> }
  39.     sequences in the rules file.  Bawk reads a line of input from
  40.     the current input file and applies every <pattern> { <action> }
  41.     in sequence to the line.
  42.     
  43.     If the <pattern> corresponding to any { <action> } is missing,
  44.     the action is applied to every line of input.  The default
  45.     { <action> } is to print the matched input line.
  46.  
  47. PATTERNS
  48.  
  49.     The <pattern>'s may consist of any valid C expression.  If the
  50.     <pattern> consists of two expressions seperated by a comma, it
  51.     is taken to be a range and the <action> is performed on all
  52.     lines of input that match the range.  <pattern>'s may contain
  53.     "regular expressions" delimited by an '@' symbol.  Regular
  54.     expressions can be thought of as a generalized "wildcard"
  55.     string matching mechanism, similar to that used by many
  56.     operating systems to specify file names.  Regular expressions
  57.     may contain any of the following characters:
  58.  
  59.         x    An ordinary character (not mentioned below)
  60.             matches that character.
  61.         '\'    The backslash quotes any character.
  62.             "\$" matches a dollar-sign.
  63.         '^'    A circumflex at the beginning of an expression
  64.             matches the beginning of a line.
  65.         '$'    A dollar-sign at the end of an expression
  66.             matches the end of a line.
  67.         '.'    A period matches any single character except
  68.             newline.
  69.         ':x'    A colon matches a class of characters described
  70.             by the character following it:
  71.         ':a'    ":a" matches any alphabetic;
  72.         ':d'    ":d" matches digits;
  73.         ':n'    ":n" matches alphanumerics;
  74.         ': '    ": " matches spaces, tabs, and other control
  75.             characters, such as newline.
  76.         '*'    An expression followed by an asterisk matches
  77.             zero or more occurrances of that expression:
  78.             "fo*" matches "f", "fo", "foo", "fooo", etc.
  79.         '+'    An expression followed by a plus sign matches
  80.             one or more occurrances of that expression:
  81.             "fo+" matches "fo", "foo", "fooo", etc.
  82.         '-'    An expression followed by a minus sign
  83.             optionally matches the expression.
  84.         '[]'    A string enclosed in square brackets matches
  85.             any single character in that string, but no
  86.             others.  If the first character in the string
  87.             is a circumflex, the expression matches any
  88.             character except newline and the characters in
  89.             the string.  For example, "[xyz]" matches "xx"
  90.             and "zyx", while "[^xyz]" matches "abc" but not
  91.             "axb".  A range of characters may be specified
  92.             by two characters separated by "-".  Note that,
  93.             [a-z] matches alphabetics, while [z-a] never
  94.             matches.
  95.  
  96.     For example, the following rules file would print every line
  97.     that contained a valid C identifier:
  98.  
  99.         @[a-zA-Z][a-zA-Z0-9]@
  100.  
  101.     And this rules file would print all lines between and including
  102.     the ones that contained the word "START" and "END":
  103.  
  104.         @START@, @END@
  105.  
  106. ACTIONS
  107.  
  108.     Actions are expressed as a subset of the C language.  All
  109.     variables are global and default to int's if not formally
  110.     declared.  Variable declarations may appear anywhere within
  111.     an action.  Only char's and int's and pointers and arrays of
  112.     char and int are allowed.  Bawk allows only decimal integer
  113.     constants to be used - no hex (0xnn) or octal (0nn). String
  114.     and character constants may contain all of the special C
  115.     escapes (\n, \r, etc.).
  116.  
  117.     Bawk supports the "if", "else", "while" and "break" flow of
  118.     control constructs, which behave exactly as in C.
  119.  
  120.     Also supported are the following unary and binary operators,
  121.     listed in order from highest to lowest precedence:
  122.  
  123.         operator           type    associativity
  124.         () []              unary   left to right
  125.         ! ~ ++ -- - * &    unary   right to left
  126.         * / %              binary  left to right
  127.         + -                binary  left to right
  128.         << >>              binary  left to right
  129.         < <= > >=          binary  left to right
  130.         == !=              binary  left to right
  131.         &                  binary  left to right
  132.         ^                  binary  left to right
  133.         |                  binary  left to right
  134.         &&                 binary  left to right
  135.         ||                 binary  left to right
  136.         =                  binary  right to left
  137.  
  138.     Comments are introduced by a '#' symbol and are terminated by
  139.     the first newline character.  The standard "/*" and "*/"
  140.     comment delimiters are not supported and will result in a
  141.     syntax error.
  142.  
  143. FIELDS
  144.  
  145.     When bawk reads a line from the current input file, the
  146.     record is automatically seperated into "fields".  A field is
  147.     simply a string of consecutive characters delimited by either
  148.     the beginning or end of line, or a "field seperator" character
  149.     Initially, the field seperators are the space and tab character.
  150.     The special unary operator '$' is used to reference one of the
  151.     fields in the current input record (line).  The fields are
  152.     numbered sequentially starting at 1.  The expression "$0"
  153.     references the entire input line.
  154.  
  155.     Similarly, the "record seperator" is used to determine the end
  156.     of an input "line", initially the newline character.
  157.     The field and record seperators may be changed programatically
  158.     by one of the actions and will remain in effect until changed
  159.     again.
  160.  
  161.     Fields behave exactly like strings; and can be used in the same
  162.     context as a character array.  These "arrays" can be considered
  163.     to have been declared as:
  164.  
  165.         char ($n)[ 128 ];
  166.  
  167.     In other words, they are 128 bytes long.  Notice that the
  168.     parentheses are necessary because the operators [] and $
  169.     associate from right to left; without them, the statement
  170.     would have parsed as:
  171.  
  172.         char $(1[ 128 ]);
  173.  
  174.     which is obviously ridiculous.
  175.  
  176.     If the contents of one of these field arrays is altered, the
  177.     "$0" field will reflect this change.  For example, this
  178.     expression:
  179.  
  180.         *$4 = 'A';
  181.  
  182.     will change the first character of the fourth field to an upper-
  183.     case letter 'A'.  Then, when the following input line:
  184.  
  185.         120 PRINT "Name         address        Zip"
  186.  
  187.     is processed, it would be printed as:
  188.  
  189.         120 PRINT "Name         Address        Zip"
  190.  
  191.     Fields may also be modified with the strcpy() function (see
  192.     below).  For example, the expression:
  193.  
  194.         strcpy( $4, "Addr." );
  195.  
  196.     applied to the same line above would yield:
  197.  
  198.         120 PRINT "Name         Addr.        Zip"
  199.  
  200. PREDEFINED VARIABLES
  201.  
  202.     The following variables are pre-defined:
  203.  
  204.         FS        Field seperator (see below).
  205.         RS        Record seperator (see below also).
  206.         NF        Number of fields in current input
  207.                 record (line).
  208.         NR        Number of records processed thus far.
  209.         FILENAME    Name of current input file.
  210.         BEGIN        A special <pattern> that matches the
  211.                 beginning of input text, before the
  212.                 first record is read.
  213.         END        A special <pattern> that matches the
  214.                 end of input text, after the last
  215.                 record has been read.
  216.  
  217.     Bawk also provides some useful builtin functions for string
  218.     manipulation and printing:
  219.  
  220.         printf(arg..)    Exactly the printf() function from C.
  221.         getline()    Reads the next record from the current
  222.                 input file and returns 0 on end of file.
  223.         nextfile()    Closes out the current input file and
  224.                 begins processing the next file in the
  225.                 list (if any).
  226.         strlen(s)    Returns the length of its string argument.
  227.         strcpy(s,t)    Copies the string "t" to the string "s".
  228.         strcmp(s,t)    Compares the "s" to "t" and returns 0 if
  229.                 they match.
  230.         toupper(c)    Returns its character argument converted
  231.                 to upper-case.
  232.         tolower(c)    Returns its character argument converted
  233.                 to lower-case.
  234.         match(s,@re@)    Compares the string "s" to the regular
  235.                 expression "re" and returns the number
  236.                 of matches found (zero if none).
  237.  
  238. EXAMPLES
  239.  
  240.     The following rules file will scan a C program, counting the
  241.     number of mismatched parentheses, brackets, and braces.
  242.  
  243.         /[()\[\]{}]/
  244.         {
  245.             parens = parens + match( $0, @(@ );
  246.             parens = parens - match( $0, @)@ );
  247.             bracks = bracks + match( $0, @[@ );
  248.             bracks = bracks - match( $0, @]@ );
  249.             braces = braces + match( $0, @{@ );
  250.             braces = braces - match( $0, @}@ );
  251.         }
  252.         END { printf("parens=%d, brackets=%d, braces=%d\n",
  253.                 parens, bracks, braces );
  254.         }
  255.  
  256.     This program will capitalize the first word in every sentence of
  257.     a document:
  258.  
  259.         BEGIN
  260.         {
  261.             RS = '.';  # set record seperator to a period
  262.         }
  263.         {
  264.             if ( match( $1, @^[a-z]@ ) )
  265.                 *$1 = toupper( *$1 );
  266.             printf( "%s\n", $0 );
  267.         }
  268.  
  269. LIMITATIONS
  270.  
  271.     Bawk was originally written in BDS C, but every attempt was made
  272.     to keep the code as portable as possible.  The program should
  273.     be compilable with any "standard" C compiler.  On CP/M systems
  274.     compiled with BDS C, bawk takes up about 24K.
  275.  
  276.     An input record may be no longer than 128 characters. If longer
  277.     records are encountered, they terminate prematurely and the
  278.     next record starts where the previous one was hacked off.
  279.  
  280.     A single pattern or action statement may be no longer than about
  281.     4K characters, excluding comments and whitespace.  Since the
  282.     program is semi-compiled the tokenized version will probably
  283.     wind up being smaller than the source code, so the 4K figure is
  284.     only approximate.
  285.  
  286. AUTHOR
  287.  
  288.     Bob Brodt
  289.     486 Linden Ave.
  290.     Bogota, NJ 07603
  291.  
  292. ACKNOWLEDGEMENTS
  293.  
  294.     The concept for bawk (and 3/4 of the name!) was taken from
  295.     the program "awk" written by Afred V. Aho, Brian W. Kernighan
  296.     and Peter J. Weinberger.  My apologies for any irreverences.
  297.  
  298.     The regular expression compiler/parser was borrowed from a
  299.     program called "grep" and has been highly modified.  Grep is
  300.     distributed by the DEC Users Society (DECUS) and is Copyright
  301.     (C) 1980 by DECUS.  The author acknowledges DECUS with a nod of
  302.     thanks for giving their general permission and okey-dokey to
  303.     copy or modify the grep program.
  304.  
  305.     UNIX is a trademark of AT&T Bell Labs.
  306.